/**
 * @swagger
 * tags:
 *   name: 考试管理
 *   description: 考试相关的接口，包括创建、查询、修改、删除考试等操作
 */

/**
 * @swagger
 * components:
 *   schemas:
 *     Exam:
 *       type: object
 *       required:
 *         - title
 *         - duration
 *         - start_time
 *         - end_time
 *       properties:
 *         title:
 *           type: string
 *           description: |
 *             考试标题
 *             * 不能为空
 *             * 长度不超过200个字符
 *           example: "2023年度软件工程期末考试"
 *         duration:
 *           type: integer
 *           description: |
 *             考试时长（分钟）
 *             * 范围：1-480分钟
 *             * 必须是整数
 *           minimum: 1
 *           maximum: 480
 *           example: 120
 *         total_score:
 *           type: integer
 *           description: |
 *             考试总分
 *             * 可选字段
 *             * 必须是正整数
 *           minimum: 1
 *           example: 100
 *         start_time:
 *           type: string
 *           format: date-time
 *           description: |
 *             考试开始时间
 *             * ISO8601格式
 *           example: "2025-06-10T09:00:00Z"
 *         end_time:
 *           type: string
 *           format: date-time
 *           description: |
 *             考试结束时间
 *             * ISO8601格式
 *           example: "2025-06-10T11:00:00Z"
 */

const express = require('express')
const { body, param } = require('express-validator')
const router = express.Router()
const examController = require('../controllers/examController')
const { auth, requireRole } = require('../middleware/auth')
const { handleValidationErrors } = require('../middleware/validation')

// 考试验证规则
const examValidation = [
  body('title')
    .isLength({ min: 1, max: 200 })
    .withMessage('考试标题不能为空且不超过200个字符'),
  body('duration')
    .isInt({ min: 1, max: 480 })
    .withMessage('考试时长必须在1-480分钟之间'),
  body('total_score')
    .optional()
    .isInt({ min: 1 })
    .withMessage('总分必须是正整数'),
  body('start_time').isISO8601().withMessage('开始时间格式不正确'),
  body('end_time').isISO8601().withMessage('结束时间格式不正确'),
]

// 路由定义
/**
 * @swagger
 * /api/exams:
 *   get:
 *     summary: 获取考试列表
 *     description: |
 *       获取系统中的所有考试信息
 *       * 需要登录才能访问
 *       * 返回考试的基本信息列表
 *     tags: [考试管理]
 *     security:
 *       - bearerAuth: []
 *     responses:
 *       200:
 *         description: 成功获取考试列表
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/Exam'
 *       401:
 *         description: |
 *           未授权访问
 *           * token无效或已过期
 */
router.get('/', auth, examController.getExams)

/**
 * @swagger
 * /api/exams/{id}:
 *   get:
 *     summary: 获取指定考试详情
 *     description: |
 *       根据考试ID获取特定考试的详细信息
 *       * 需要登录才能访问
 *     tags: [考试管理]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: 考试ID
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: 成功获取考试信息
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Exam'
 *       404:
 *         description: 考试不存在
 */
router.get(
  '/:id',
  auth,
  param('id').isInt(),
  handleValidationErrors,
  examController.getExam
)

/**
 * @swagger
 * /api/exams:
 *   post:
 *     summary: 创建新考试
 *     description: |
 *       创建一个新的考试
 *       * 仅管理员可操作
 *       * 需要提供完整的考试信息
 *     tags: [考试管理]
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/Exam'
 *     responses:
 *       201:
 *         description: 考试创建成功
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Exam'
 *       400:
 *         description: |
 *           输入验证错误
 *           * 必填字段缺失
 *           * 字段格式错误
 *           * 时间格式错误
 *       401:
 *         description: 未授权访问
 *       403:
 *         description: 权限不足，需要管理员权限
 */
router.post(
  '/',
  auth,
  requireRole(['admin']),
  examValidation,
  handleValidationErrors,
  examController.createExam
)

/**
 * @swagger
 * /api/exams/{id}:
 *   put:
 *     summary: 更新考试信息
 *     description: |
 *       更新指定考试的信息
 *       * 仅管理员可操作
 *       * 可以更新考试的任意字段
 *     tags: [考试管理]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: 考试ID
 *         schema:
 *           type: integer
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/Exam'
 *     responses:
 *       200:
 *         description: 考试更新成功
 *       400:
 *         description: 输入验证错误
 *       401:
 *         description: 未授权访问
 *       403:
 *         description: 权限不足，需要管理员权限
 *       404:
 *         description: 考试不存在
 */
router.put(
  '/:id',
  auth,
  requireRole(['admin']),
  param('id').isInt(),
  handleValidationErrors,
  examController.updateExam
)

/**
 * @swagger
 * /api/exams/{id}:
 *   delete:
 *     summary: 删除考试
 *     description: |
 *       删除指定的考试
 *       * 仅管理员可操作
 *       * 删除后不可恢复
 *     tags: [考试管理]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: 考试ID
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: 考试删除成功
 *       401:
 *         description: 未授权访问
 *       403:
 *         description: 权限不足，需要管理员权限
 *       404:
 *         description: 考试不存在
 */
router.delete(
  '/:id',
  auth,
  requireRole(['admin']),
  param('id').isInt(),
  handleValidationErrors,
  examController.deleteExam
)

/**
 * @swagger
 * /api/exams/{id}/stats:
 *   get:
 *     summary: 获取考试统计信息
 *     description: |
 *       获取指定考试的统计信息
 *       * 仅管理员可访问
 *       * 包含参与人数、平均分等统计数据
 *     tags: [考试管理]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: 考试ID
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: 成功获取统计信息
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 total_participants:
 *                   type: integer
 *                   description: 参与考试的总人数
 *                 average_score:
 *                   type: number
 *                   description: 平均分
 *                 highest_score:
 *                   type: number
 *                   description: 最高分
 *                 lowest_score:
 *                   type: number
 *                   description: 最低分
 *       401:
 *         description: 未授权访问
 *       403:
 *         description: 权限不足，需要管理员权限
 *       404:
 *         description: 考试不存在
 */
router.get(
  '/:id/stats',
  auth,
  requireRole(['admin']),
  param('id').isInt(),
  handleValidationErrors,
  examController.getExamStats
)

module.exports = router
